{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "cb9d00f5-9613-471e-a4bb-6181311bf73b",
   "metadata": {},
   "source": [
    "# Tutorial: Using the API functionality of binary_c-python\n",
    "This notebook shows how to use the API functions that interface with binary_c. It usually is better to use wrapper functions that internally use these API functions, because most of the output here is very raw\n",
    "\n",
    "Binaryc-python uses the Python-C extension framework to interface Python with C. The sourcecode for this is contained in `src/binary_c_python.c`, and the functions are available via `from binarycpython import _binary_c_bindings`.\n",
    "\n",
    "The following functions are available through the API: (run cell below)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "ded7eaf6-e1ba-46c2-9f6f-9ebcb14a264d",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Help on module binarycpython._binary_c_bindings in binarycpython:\n",
      "\n",
      "NAME\n",
      "    binarycpython._binary_c_bindings - Module to interface the Binary_c API with python.\n",
      "\n",
      "FUNCTIONS\n",
      "    free_persistent_data_memaddr_and_return_json_output(...)\n",
      "        Frees the persistent_data memory and returns the json output.\n",
      "        \n",
      "        Arguments:\n",
      "                store capsule: capsule containing the memory adress of the persistent data object (contains the ensemble)\n",
      "    \n",
      "    free_store_memaddr(...)\n",
      "        Frees the store memaddr.\n",
      "        \n",
      "        Arguments:\n",
      "                store capsule: capsule containing the memory adress of the store object\n",
      "    \n",
      "    return_arglines(...)\n",
      "        Return the default args for a binary_c system\n",
      "        \n",
      "        Arguments:\n",
      "                No arguments.\n",
      "    \n",
      "    return_help(...)\n",
      "        Return the help info for a given parameter\n",
      "        \n",
      "        Arguments:\n",
      "                parameter: parameter name.\n",
      "    \n",
      "    return_help_all(...)\n",
      "        Return an overview of all the parameters, their description, categorized in sections\n",
      "        \n",
      "        Arguments:\n",
      "                No arguments.\n",
      "    \n",
      "    return_maximum_mass_ratio_for_RLOF(...)\n",
      "        Returns a string containing the maximum mass ratio for which a binary system does not RLOF at ZAMS. Please use the wrapper functions in utils for this except when you know what you're doing.\n",
      "        \n",
      "        Arguments:\n",
      "                argstring: argument string for binary_c\n",
      "                (opt) store_capsule: capsule containing memory adress for the store object.unction. Default = Null\n",
      "    \n",
      "    return_minimum_orbit_for_RLOF(...)\n",
      "        Returns a string containing the minimum orbit and separation for which a binary system does not RLOF at ZAMS. Please use the wrapper functions in utils for this except when you know what you're doing.\n",
      "        \n",
      "        Arguments:\n",
      "                argstring: argument string for binary_c\n",
      "                (opt) store_capsule: capsule containing memory adress for the store object.unction. Default = Null\n",
      "    \n",
      "    return_persistent_data_memaddr(...)\n",
      "        Return the store memory adress that will be passed to run_population\n",
      "        \n",
      "        Arguments:\n",
      "                No arguments.\n",
      "    \n",
      "    return_store_memaddr(...)\n",
      "        Return the store memory adress that will be passed to run_population\n",
      "        \n",
      "        Arguments:\n",
      "                No arguments.\n",
      "    \n",
      "    return_version_info(...)\n",
      "        Return the version information of the used binary_c build\n",
      "        \n",
      "        Arguments:\n",
      "                No arguments.\n",
      "    \n",
      "    run_system(...)\n",
      "        Function to run a system. This is a general function that will be able to handle different kinds of situations: single system run with different settings, population run with different settings, etc. To avoid having too many functions doing slightly different things.\n",
      "        \n",
      "        Arguments:\n",
      "                argstring: argument string for binary_c\n",
      "                (opt) custom_logging_func_memaddr: memory address value for custom logging function. Default = -1 (None)\n",
      "                (opt) store_memaddr: memory adress of the store. Default = -1 (None)\n",
      "                (opt) write_logfile: Boolean (in int form) for whether to enable the writing of the log function. Default = 0\n",
      "                (opt) population: Boolean (in int form) for whether this system is part of a population run. Default = 0.\n",
      "    \n",
      "    test_func(...)\n",
      "        Function that contains random snippets. Do not expect this to remain available, or reliable. i.e. dont use it.\n",
      "\n",
      "FILE\n",
      "    /home/david/.pyenv/versions/3.9.9/envs/binarycpython3.9.9/lib/python3.9/site-packages/binarycpython/_binary_c_bindings.cpython-39-x86_64-linux-gnu.so\n",
      "\n",
      "\n"
     ]
    }
   ],
   "source": [
    "from binarycpython import _binary_c_bindings\n",
    "help(_binary_c_bindings)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7ddede71-ffaa-4b24-aece-e94128a60d7f",
   "metadata": {},
   "source": [
    "There are three main categories of functions:\n",
    "\n",
    "- Functions to get information from binary_c: these can be used to evolve systems, and get utility information from binary_c.\n",
    "    - run_system\n",
    "    - return_minimum_orbit_for_RLOF\n",
    "    - return_maximum_mass_ratio_for_RLOF\n",
    "    - return_help\n",
    "    - return_help_all\n",
    "    - return_arglines\n",
    "\n",
    "- Memory creation functions: these can be used to have binary_c allocate memory which is used or written to by binary_c\n",
    "    - return_persistent_data_memaddr\n",
    "    - return_store_memaddr\n",
    "\n",
    "- Memory freeing functions: These can be used to free the allocated memory, and in the case of persistent memory it will also return the contents of the ensemble\n",
    "    - free_persistent_data_memaddr_and_return_json_output\n",
    "    - free_store_memaddr"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0dd3e115-1571-42f7-9ab9-cf7688fa28c1",
   "metadata": {},
   "source": [
    "## Example usage:"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c5015daa-35ab-4736-a04d-f3cbe661638c",
   "metadata": {},
   "source": [
    "### Setting up, using and freeing store"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "10a74d5a-a3d5-4543-a5bc-20d1fe885bb4",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<capsule object \"STORE\" at 0x7f87e3369720>\n",
      "SINGLE_STAR_LIFETIME 10 28.4838\n",
      "\n"
     ]
    }
   ],
   "source": [
    "# allocating store memory\n",
    "store_memaddr = _binary_c_bindings.return_store_memaddr()\n",
    "print(store_memaddr)\n",
    "\n",
    "# Here we set up the argument string that is passed to the bindings\n",
    "argstring = \"\"\"\n",
    "binary_c M_1 {M_1} orbital_period {orbital_period} eccentricity {eccentricity} metallicity {metallicity} max_evolution_time {max_evolution_time}\n",
    "\"\"\".format(\n",
    "    M_1=10,\n",
    "    orbital_period=4500,\n",
    "    eccentricity=0.0,\n",
    "    metallicity=0.02,\n",
    "    max_evolution_time=15000,\n",
    ").strip()\n",
    "\n",
    "#\n",
    "output = _binary_c_bindings.run_system(argstring, store_memaddr=store_memaddr)\n",
    "print(output)\n",
    "\n",
    "# Free the store\n",
    "_binary_c_bindings.free_store_memaddr(store_memaddr)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e9da5fc6-e680-483c-982e-4819767ed5b2",
   "metadata": {},
   "source": [
    "### Getting information from binary_c"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "24f7ffe5-0076-459d-a37f-254e10d0d9f9",
   "metadata": {},
   "source": [
    "We can get information for a parameter via return_help(parameter_name):\n",
    "This will return an unparsed output"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "318874f6-7acf-49bb-9786-299d4dffc0b3",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "binary_c help for variable : M_1 <Float>\n",
      "\n",
      "The initial mass of star one (in solar units, internally this is star index 0).\n",
      "\n",
      "Default : 0\n",
      "Random variation : log-spaced double between 0.1 and 100 \n",
      "\n",
      "\n",
      "\n",
      "\n"
     ]
    }
   ],
   "source": [
    "print(_binary_c_bindings.return_help('M_1'))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f7fafce6-a522-43ac-a0c2-15a3db393b49",
   "metadata": {},
   "source": [
    "We can get information on all available parameters via return_help(parameter_name):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "d7e757ae-579c-42a2-a310-f0401b7800e8",
   "metadata": {
    "scrolled": true,
    "tags": []
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "############################################################\n",
      "##### Section Stars\n",
      "############################################################\n",
      "metallicity : This sets the metallicity of the stars, i.e. the amount (by mass) of matter which is not hydrogen or helium. If you are using the BSE algorithm, this must be 1e-4 <= metallicity <= 0.03. See also nucsyn_metallicity and effective_metallicity. : (null)\n",
      "effective_metallicity : This sets effective metallicity of stars as used in routines like the Schneider wind loss. If not set, or set to DEFAULT_TO_METALLICITY (==-1, the default), this is just the same as metallicity. The main difference between effective_metallicity and metallicity is the range of validity: 0 <= effective_metallicity <= 1, while metallicity's range of validity is limited by the stellar evolution algorithm (so, for BSE, is 1e-4 <= metallicity <= 0.03). : (null)\n",
      "M_1 : The initial mass of star one (in solar units, internally this is star index 0). : (null)\n",
      "M_2 : The initial mass of star two (in solar units, internally this is star index 1). : (null)\n",
      "M_3 : The initial mass of star three (in solar units, internally this is star index 2). : (null)\n",
      "M_4 : The initial mass of star four (in solar units, internally this is star index 3). : (null)\n",
      "(abridged)\n"
     ]
    }
   ],
   "source": [
    "print('\\n'.join(_binary_c_bindings.return_help_all().splitlines()[:10]))\n",
    "print(\"(abridged)\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "bfec32cf-7240-4a82-ac30-b3d99a018a28",
   "metadata": {},
   "source": [
    "We can get all the parameter names and their default values with return_arglines(): (abridged output)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "3d29ca9d-ac66-4f9e-81cf-2edd14a98b79",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "__ARG_BEGIN\n",
      "defaults_set = 2022a\n",
      "skip_bad_args = 0\n",
      "metallicity = 0.02\n",
      "(abridged)\n"
     ]
    }
   ],
   "source": [
    "print('\\n'.join(_binary_c_bindings.return_arglines().splitlines()[:4]))\n",
    "print(\"(abridged)\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e8b1c8b6-a878-43f4-bc36-1b20b3e66c6f",
   "metadata": {},
   "source": [
    "Lastly, we can ask binary_c to determine the minimum period or maximum mass for RLOF at the ZAMS: Both of them need an argstring as input."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "e517f561-09c6-419d-ba89-d9cb61e6ebab",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "MINIMUM SEPARATION 0.31\n",
      "MINIMUM PERIOD 0.00632092\n",
      "\n"
     ]
    }
   ],
   "source": [
    "store_memaddr = _binary_c_bindings.return_store_memaddr()\n",
    "argstring = \"\"\"\n",
    "binary_c M_1 {M_1} orbital_period {orbital_period} eccentricity {eccentricity} metallicity {metallicity} max_evolution_time {max_evolution_time}\n",
    "\"\"\".format(\n",
    "    M_1=10,\n",
    "    orbital_period=4500.0,\n",
    "    eccentricity=0.0,\n",
    "    metallicity=0.02,\n",
    "    max_evolution_time=15000,\n",
    ").strip()\n",
    "\n",
    "output = _binary_c_bindings.return_minimum_orbit_for_RLOF(argstring, store_capsule=store_memaddr)\n",
    "print(output)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.9.9"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}